NNX migration prep (4/N): sharding tools and Linen<->NNX checkpoint utilities#3525
Draft
ecnal-cienet wants to merge 4 commits intomainfrom
Draft
NNX migration prep (4/N): sharding tools and Linen<->NNX checkpoint utilities#3525ecnal-cienet wants to merge 4 commits intomainfrom
ecnal-cienet wants to merge 4 commits intomainfrom
Conversation
Codecov Report❌ Patch coverage is 📢 Thoughts on this report? Let us know! |
ecnal-cienet
force-pushed
the
feat/nnx-linen-converter-and-sharding-tools
branch
from
63adaef to
1fe3f78
Compare
- pure_nnx: a flag to to choose pure NNX logic when NNX and linen models co-exist. - init_state_fn: a function to initialize the model state for the training. It will be set to different function for NNX and Linen.
- Add utils to manipulate the NNX shardings with abstract state of a
model
- also add unit tests for the utils
- Extract mesh creation function to maxtext_utils.get_mesh_from_config()
- also add unit tests for this func
Note:
flax v0.12 has DeprecationWarning in multiple places:
- DeprecationWarning: '.value' access is now deprecated. Use
variable.get_value() or variable[...] (for [Array]).
- DeprecationWarning: 'VariableState' was removed, this is just
an alias to 'Variable'. Plase use 'Variable' directly instead.
But since the code needs to work with post-training, which currently
requires flax v0.11, we didn't change code for these warnings.
- Add TrainStateNNX (layers/train_state_nnx.py) with checkpoint and unit tests - Refactor model_creation_utils with create_nnx_abstract_model(); add NNX support to muon_utils - Add get_abstract_state_nnx() and get_nnx_named_sharding_with_scan_axis() to maxtext_utils.py - Wire NNX train state into train.py and train_utils.py with pure_nnx dispatch
…ison utility - modify print_shardings_params to support NNX (maxtext_utils.py) - add --pure_nnx flag to run_sharding_dump.py - add bidirectional Linen<->NNX checkpoint conversion utility (linen_nnx_converter.py) - add checkpoint comparison utility for Linen vs NNX validation (compare_linen_nnx_checkpoint.py)
ecnal-cienet
force-pushed
the
feat/nnx-linen-converter-and-sharding-tools
branch
from
1fe3f78 to
8aa93c4
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
NNX Migration Route Map
pure_nnxflag,init_state_fn,TrainStateNNX, NNX utils. Linen workflow unchanged. (PR #3427)get_abstract_state_nnx,get_named_sharding_nnx,set_named_sharding_nnx,get_partition_spec_nnx,get_mesh_from_config. (PR #3470)TrainStateNNX, model creation, gradient accumulation, checkpointing, and training loop dispatch. (PR #3500)pure_nnx=Trueas default.Description
Sharding diagnostics
maxtext_utils.py—print_shardings_paramsnow dispatches onpure_nnx: for NNX models it iterates over the flatnnx.Staterather than the Linenparamstree.tests/utils/run_sharding_dump.py—run_single_dump()now propagates--pure_nnx=trueto the sharding-dump subprocess when the flag is set, enabling NNX sharding dumps without manual flag threading.Linen ↔ NNX checkpoint converter
src/maxtext/checkpoint_conversion/linen_nnx_converter.py— a standalone CPU-only script that bidirectionally converts Orbax checkpoints between Linen and NNX formats.Key transformations handled:
paramstreeopt_statestepparams/params/<model>→model/<model>+{value:}wrappersparamslevel frommu/nuoptimizer/layers_Narrays →layerstensor (axis 1)paramslevellayerstensor →layers_Nper-layer arrays--directionacceptslinen_to_nnx,nnx_to_linen, orauto(detects format from checkpoint keys).Checkpoint comparison utility
src/maxtext/checkpoint_conversion/compare_linen_nnx_checkpoint.py— compares tree structure, shapes, and optionally values between any two Orbax checkpoints (Linen vs NNX, or same-format). Auto-detects format and applies cross-format normalization (layer axis transposition,{value:}unwrapping, RNG filtering) only when needed.Tests
Unit tests:
Checklist
Before submitting this PR, please make sure (put X in square brackets):
gemini-reviewlabel.